# Техническая документация
## Описание
Техническая документация подразделяется на пользовательскую и внутреннюю. **Пользовательская документация** включает в себя инструкции по использованию и установке продукта, описания API, системные требования и прочие документы, предназначенные для конечного пользователя. **Внутреннюю документацию** в свою очередь можно разделить на продуктовую (описания архитектуры проекта, мануалы по разворачиванию сред разработки, воспроизведению результатов экспериментов, UX документация) и процессуальную (гайдлайны по написанию кода и процедуре code review, документацию по командным процессам, отчёты для менеджмента, планы и roadmaps).
## Почему ветка важна?
Для тимлида:
- Помогает всегда оставаться в курсе актуального состояния проекта и делиться этой информацией с бизнесом
- Облегчает процесс онбординга новых членов команды
- Упрощает коммуникацию с пользователями и stakeholders

Для команды
- Значительно снижается сложность вникания в новый проект
- Всегда есть актуальный референс, любой член команды может понять, что происходит в других частях проекта
- Увеличивается bus factor, происходит распространение знания внутри команды
- Зачастую сам процесс написания документации улучшает понимание архитектуры проекта и приводит к обнаружению багов или появлению новых идей

Для пользователей
- Легче пользоваться продуктом, возникает меньше вопросов и ошибок
## Что будет, если её не делать?
- Внутренняя документация
    - Новые сотрудники будут тратить значительно больше времени на погружение в проект. Также они будут отнимать драгоценное время у членов команды, задавая вопросы, которые легко могли быть покрыты документацией
    - Проект будет обрастать незадокументированными фичами, знание о которых будет иметься лишь у нескольких людей, и даже эти люди в какой-то момент о них забудут
- Пользовательская документация
    - Возрастает нагрузка на техническую поддержку
    - Увеличивается недовольство пользователей

## На кого может быть делегирована?
На любого разработчика или технического писателя
## Примеры поведения
### Примеры плохого поведения
- Обновление документации не включается в Definition of Done или не выносится отдельными PBI
- Затраты времени на написание документации не учитываются при планировании
- Документация не версионируется
- Важные изменения документации не проходят процедуру ревью
- Документация написана слишком длинно и нудно, содержит устаревшую и ненужную информацию
- Документация пишется не итеративно, а огромными пластами
- Документация пишется "для галочки", её ценность для команды и пользователей не определена, и её никто не читает

### Примеры хорошего поведения
- У команд есть единые шаблоны, правила оформления и стиля для создания документации
- У каждого документа имеется понятная целевая аудитория (пользователи, другие команды, члены команды, менеджмент)
- Документация хранится в едином удобном месте с функцией поиска, а не раскидана по Google Docs, Confluence, Wiki, Redmine и бумажкам в офисе
- Используется методология [Docs-as-code](https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html) - документация пишется в текстовом редакторе (например, в формате Markdown), хранится в репозитории, версионируется, тестируется и проходит процедуру peer review, считаются метрики качества (например, [readability](https://en.wikipedia.org/wiki/Readability)), новые версии автоматически публикуются
- Документация хорошо оформлена, важные места выделены и бросаются в глаза
- Документация содержит ссылки на другие релевантные документы
- Документация время от времени тестируется на актуальность
- Обновление документации автоматизируется (насколько это возможно)
- Появление новой важной документации сопровождается туториалами и воркшопами для целевой аудитории
- Документация содержит средства визуализации (диаграммы, графики)

## Способы прокачки
### Практика
1. Полезно читать документацию опенсорсных проектов и других команд и заимствовать лучшие идеи
2. Регулярно структурируйте имеющуюся документацию и оценивайте её качество для разных частей проекта
3. В запущенных случаях может быть полезен внешний аудит документации
4. Для каждого типа документации нужно определить оптимальный способ написания (по ходу разработки vs [document late](http://agilemodeling.com/essays/documentLate.htm))
5. Найдите правильный баланс между отсутствием документации и избыточной документацией. Соберите обратную связь от разных групп (разработчики, пользователи, тестировщики, другие команды)
6. Не бойтесь пробовать нестандартные формы документации - например, видео-дискуссии или подкасты

## Консультации
- [Telegram-чат TL Bootcamp](https://tlinks.run/tlbootcamp)

## Теория
### Подкасты
- [SE Radio - Agile Documentation](https://www.se-radio.net/2006/10/episode-31-agile-documentation/)
### Статьи
- [Technical Documentation in Software Development](https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/)
- [A Roadmap to Agile Documentation](https://www.infoq.com/articles/roadmap-agile-documentation/)
- [Model Cards for Model Reporting](https://arxiv.org/abs/1810.03993)
